Usenet 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / sources / unix / volume6 / rpc2 / part02 < prev next >

Wrap

Internet Message Format | 1986-11-30 | 52.1 KB

Subject: v06i090: Sun RPC Source (rpc2), Part02/11 Newsgroups: mod.sources Approved: rs@mirror.UUCP Submitted by: sun!ferne!marks (Mark Stein) Mod.sources: Volume 6, Issue 90 Archive-name: rpc2/Part02 [ All I have done is verify that the shar files unpack correctly. -r$ ] Sun RPC source (part 2 of 11). This software package contains code and documentation for Revision 3.0 of the Sun Remote Procedure Call library. In addition, a beta version of the XDR/RPC protocol compiler is included. Comments about this latest release may be mailed to sun!rpc or rpc@sun.com. Sun RPC is a product of Sun Microsystems, Inc. and is provided for unrestricted use provided that this legend is included on all tape media and as a part of the software program in whole or part. Users may copy or modify Sun RPC without charge, but are not authorized to license or distribute it to anyone else except as part of a product or program developed by the user. - - - - - - - - - C U T - H E R E - - - - - - - - - - - - - - - - - - #! /bin/sh # This is a shell archive, meaning: # 1. Remove everything above the #! /bin/sh line. # 2. Save the resulting text in a file. # 3. Execute the file with /bin/sh (not csh) to create: # rpc/doc/rpc.prog.p1 # This archive created: Mon Jul 14 16:54:58 1986 export PATH; PATH=/bin:/usr/bin:$PATH for d in rpc rpc/doc rpc/rpclib rpc/tools rpc/toys rpc/rpclib/profiled rpc/rpcgen rpc/rpcgen/test do if test ! -d $d then echo "shar: Making directory $d" mkdir $d chmod 755 $d fi done echo shar: "extracting 'rpc/doc/rpc.prog.p1'" '(49365 characters)' if test -f 'rpc/doc/rpc.prog.p1' then echo shar: "will not over-write existing file 'rpc/doc/rpc.prog.p1'" else sed 's/^X//' << \SHAR_EOF > 'rpc/doc/rpc.prog.p1' X.PL RIGHT X.TL XRemote Procedure Call X.br XProgramming Guide X.bp X.NH XIntroduction X.LP XThis document is intended for programmers Xwho wish to write network applications Xusing remote procedure calls (explained below), Xthus avoiding low-level system primitives based on sockets. XThe reader must be familiar with the C programming language, Xand should have a working knowledge of network theory. X.LP XPrograms that communicate over a network Xneed a paradigm for communication. XA low-level mechanism might Xsend a signal on the arrival of incoming packets, Xcausing a network signal handler to execute. XA high-level mechanism would be the Ada X.LW rendezvous . XThe method used at Sun is the XRemote Procedure Call (RPC) paradigm, Xin which a client communicates with a server. XIn this process, Xthe client first calls a procedure to send a data packet to the server. XWhen the packet arrives, the server calls a dispatch routine, Xperforms whatever service is requested, sends back the reply, Xand the procedure call returns to the client. X.NH 2 XLayers of RPC X.LP XThe RPC interface is divided into three layers. XThe highest layer is totally transparent to the programmer. XTo illustrate, Xat this level a program can contain a call to X.LW rnusers() , Xwhich returns the number of users on a remote machine. XYou don't have to be aware that RPC is being used, Xsince you simply make the call in a program, Xjust as you would call X.LW malloc() . X.LP XAt the middle layer, the routines X.LW registerrpc() Xand X.LW callrpc() Xare used to make RPC calls: X.LW registerrpc() Xobtains a unique system-wide number, while X.LW callrpc() Xexecutes a remote procedure call. XThe X.LW rnusers() Xcall is implemented using these two routines. XThe middle-layer routines are designed for most common applications, Xand shield the user from knowing about sockets. X.LP XThe lowest layer is for more sophisticated applications, Xsuch as altering the defaults of the routines. XAt this layer, you can explicitly manipulate Xsockets that transmit RPC messages. XThis level should be avoided if possible. X.LP XSection 2 of this manual illustrates use of the highest two layers Xwhile Section 3 presents the low-level interface. XSection 4 of the manual discusses miscellaneous topics. XThe final section summarizes Xall the entry points into the RPC system. X.LP XAlthough this document only discusses the interface to C, Xremote procedure calls can be made from any language. XEven though this document discusses RPC Xwhen it is used to communicate Xbetween processes on different machines, Xit works just as well for communication Xbetween different processes on the same machine. X.NH 2 XThe RPC Paradigm X.LP XHere is a diagram of the RPC paradigm: X.LP X.PL FULL X.PS XL1: arrow down 1i "client " rjust "program " rjust XL2: line right 1.5i "\fLcallrpc()\fP" "function" Xmove up 1.5i; line dotted down 6i; move up 4.5i Xarrow right 1i XL3: arrow down 1i "execute " rjust "request " rjust XL4: arrow right 1.5i "call" "service" XL5: arrow down 1i " service" ljust " executes" ljust XL6: arrow left 1.5i "\fLreturn\fP" "answer" XL7: arrow down 1i "request " rjust "completed " rjust XL8: line left 1i Xarrow left 1.5i "\fLreturn\fP" "reply" XL9: arrow down 1i "program " rjust "continues " rjust Xline dashed down from L2 to L9 Xline dashed down from L4 to L7 Xline dashed up 1i from L3 "service " rjust "daemon " rjust Xarrow dashed down 1i from L8 Xmove right 1i from L3 Xbox invis "Machine B" Xmove left 1.2i from L2; move down Xbox invis "Machine A" X.PE X.FN "Network Communication with the Remote Procedure Call" X.PL RIGHT X.bp X.NH XHigher Layers of RPC X.NH 2 XHighest Layer X.LP XImagine you're writing a program that needs to know Xhow many users are logged into a remote machine. XYou can do this by calling the library routine X.LW rnusers() , Xas illustrated below: X.BS X.LS X#include <stdio.h> X.sp.5 Xmain(argc, argv) X int argc; X char **argv; X{ X unsigned num; X.sp.5 X if (argc < 2) { X fprintf(stderr, "usage: rnusers hostname\en"); X exit(1); X } X if ((num = rnusers(argv[1])) < 0) { X fprintf(stderr, "error: rnusers\en"); X exit(-1); X } X printf("%d users on %s\en", num, argv[1]); X exit(0); X} X.Lf X.BE XRPC library routines such as X.LW rnusers() Xare in the RPC services library X.LW librpcsvc.a . XThus, the program above should be compiled with X.BS X.LS X% cc \fIprogram\fP.c -lrpcsvc X.Lf X.BE XThis routine, and other RPC library routines, Xare documented in section 3R of the X.I "System Interface Manual for the Sun Workstation" . XHere is a table of RPC service library routines Xavailable to the C programmer: X.TN "RPC Service Library Routines" X.TS Xbox; XcfBI s Xc c XlfL l. X.sp.5 X\s+2RPC Service Library Routines\s-2 X.sp.5 X_ X\fIroutine description\fP X_ Xrnusers() return number of users on remote machine Xrusers() return information about users on remote machine Xhavedisk() determine if remote machine has disk Xrstat() get performance data from remote kernel Xrwall() write to specified remote machines Xgetmaster() get name of YP master Xgetrpcport() get RPC port number Xyppasswd() update user password in yellow pages X.TE X.LP XThe other RPC services \(em X.LW ether , X.LW mount , X.LW rquota , Xand X.LW spray X\(em are not available to the C programmer as library routines. XThey do, however, Xhave RPC program numbers so they can be invoked with X.LW callrpc() , Xwhich will be discussed in the next section. X.bp X.NH 2 XIntermediate Layer X.LP XThe simplest interface, which explicitly makes RPC Xcalls, uses the functions X.LW callrpc() Xand X.LW registerrpc() . XUsing this method, another way to get the number of remote users is: X.BS X.LS X#include <stdio.h> X#include <rpcsvc/rusers.h> X.sp.5 Xmain(argc, argv) X int argc; X char **argv; X{ X unsigned long nusers; X.sp.5 X if (argc < 2) { X fprintf(stderr, "usage: nusers hostname\en"); X exit(-1); X } X if (callrpc(argv[1], X RUSERSPROG, RUSERSVERS, RUSERSPROC_NUM, X xdr_void, 0, xdr_u_long, &nusers) != 0) { X fprintf(stderr, "error: callrpc\en"); X exit(1); X } X printf("%d users on %s\en", nusers, argv[1]); X exit(0); X} X.Lf X.BE XA program number, version number, and procedure number Xdefines each RPC procedure. XThe program number defines a group Xof related remote procedures, each of which has a different Xprocedure number. XEach program also has a version number, Xso when a minor change is made to a remote service X(adding a new procedure, for example), Xa new program number doesn't have to be assigned. XWhen you want to call a procedure to Xfind the number of remote users, you look up the appropriate Xprogram, version and procedure numbers Xin a manual, similar to when you look up the name of memory Xallocator when you want to allocate memory. X.LP XThe simplest routine in the RPC library Xused to make remote procedure calls is X.LW callrpc() . XIt has eight parameters. XThe first is the name of the remote machine. XThe next three parameters Xare the program, version, and procedure numbers. XThe following two parameters Xdefine the argument of the RPC call, and the final two parameters Xare for the return value of the call. XIf it completes successfully, X.LW callrpc() Xreturns zero, but nonzero otherwise. XThe exact meaning of the return codes is found in X.LW <rpc/clnt.h> , Xand is in fact an X.LW "enum clnt_stat" Xcast into an integer. X.LP XSince data types may be represented differently on different machines, X.LW callrpc() Xneeds both the type of the RPC argument, as well as Xa pointer to the argument itself (and similarly for the result). For X.LW RUSERSPROC_NUM , Xthe return value is an X.LW "unsigned long" , Xso X.LW callrpc() Xhas X.LW xdr_u_long Xas its first return parameter, which says Xthat the result is of type X.LW "unsigned long" , Xand X.LW &nusers Xas its second return parameter, Xwhich is a pointer to where the long result will be placed. Since X.LW RUSERSPROC_NUM Xtakes no argument, the argument parameter of X.LW callrpc() Xis X.LW xdr_void . X.LP XAfter trying several times to deliver a message, if X.LW callrpc() Xgets no answer, it returns with an error code. XThe delivery mechanism is UDP, Xwhich stands for User Datagram Protocol. XMethods for adjusting the number of retries Xor for using a different protocol require you to use the lower Xlayer of the RPC library, discussed later in this document. XThe remote server procedure Xcorresponding to the above might look like this: X.BS X.LS Xchar * Xnuser(indata) X char *indata; X{ X static int nusers; X.sp.5 X /* X * code here to compute the number of users X * and place result in variable nusers X */ X return((char *)&nusers); X} X.Lf X.BE X.LP XIt takes one argument, which is a pointer to the input Xof the remote procedure call (ignored in our example), Xand it returns a pointer to the result. XIn the current version of C, Xcharacter pointers are the generic pointers, Xso both the input argument and the return value are cast to X.LW "char *" . X.LP XNormally, a server registers all of the RPC calls it plans Xto handle, and then goes into an infinite loop waiting to service requests. XIn this example, there is only a single procedure Xto register, so the main body of the server would look like this: X.BS X.LS X#include <stdio.h> X#include <rpcsvc/rusers.h> X.sp.5 Xchar *nuser(); X.sp.5 Xmain() X{ X registerrpc(RUSERSPROG, RUSERSVERS, RUSERSPROC_NUM, X nuser, xdr_void, xdr_u_long); X svc_run(); /* never returns */ X fprintf(stderr, "Error: svc_run returned!\en"); X exit(1); X} X.Lf X.BE X.LP XThe X.LW registerrpc() Xroutine establishes what C procedure Xcorresponds to each RPC procedure number. XThe first three parameters, X.LW RUSERPROG , X.LW RUSERSVERS , Xand X.LW RUSERSPROC_NUM Xare the program, version, and procedure numbers Xof the remote procedure to be registered; X.LW nuser() Xis the name of the C procedure implementing it; Xand X.LW xdr_void Xand X.LW xdr_u_long Xare the types of the input to and output from the procedure. X.LP XOnly the UDP transport mechanism can use X.LW registerrpc() ; Xthus, it is always safe in conjunction with calls generated by X.LW callrpc() . X.LP XWarning: the UDP transport mechanism can only deal with Xarguments and results less than 8K bytes in length. X.NH 2 XAssigning Program Numbers X.LP XProgram numbers are assigned in groups of 0x20000000 (536870912) Xaccording to the following chart: X.BS X.LS X 0 - 1fffffff defined by sun X20000000 - 3fffffff defined by user X40000000 - 5fffffff transient X60000000 - 7fffffff reserved X80000000 - 9fffffff reserved Xa0000000 - bfffffff reserved Xc0000000 - dfffffff reserved Xe0000000 - ffffffff reserved X.Lf X.BE XSun Microsystems administers the first group of numbers, Xwhich should be identical for all Sun customers. XIf a customer develops an application that might be of general interest, Xthat application should be given an assigned number in the first range. XThe second group of numbers is reserved for specific customer applications. XThis range is intended primarily for debugging new programs. XThe third group is reserved for applications that Xgenerate program numbers dynamically. XThe final groups are reserved for future use, and should not be used. X.LP XTo register a protocol specification, Xsend a request by network mail to X.LW sun!rpc , Xor write to: X.DS XRPC Administrator XSun Microsystems X2550 Garcia Ave. XMountain View, CA 94043 X.DE XPlease include a complete protocol specification, Xsimilar to those in this manual for NFS and YP. XYou will be given a unique program number in return. X.NH 2 XPassing Arbitrary Data Types X.LP XIn the previous example, the RPC call passes a single X.LW "unsigned long" . XRPC can handle arbitrary data structures, regardless of Xdifferent machines' byte orders or structure layout conventions, Xby always converting them to a network standard called X.I "eXternal Data Representation" X(XDR) before Xsending them over the wire. XThe process of converting from a particular machine representation Xto XDR format is called X.I serializing , Xand the reverse process is called X.I deserializing . XThe type field parameters of X.LW callrpc() Xand X.LW registerrpc() Xcan be a built-in procedure like X.LW xdr_u_long() Xin the previous example, or a user supplied one. XXDR has these built-in type routines: X.BS X.LS Xxdr_int() xdr_u_int() xdr_enum() Xxdr_long() xdr_u_long() xdr_bool() Xxdr_short() xdr_u_short() xdr_string() X.Lf X.BE XAs an example of a user-defined type routine, Xif you wanted to send the structure X.BS X.LS Xstruct simple { X int a; X short b; X} simple; X.Lf X.BE Xthen you would call X.LW callrpc() Xas X.BS X.LS Xcallrpc(hostname, PROGNUM, VERSNUM, PROCNUM, X xdr_simple, &simple ...); X.Lf X.BE Xwhere X.LW xdr_simple() Xis written as: X.BS X.LS X#include <rpc/rpc.h> X.sp.5 Xxdr_simple(xdrsp, simplep) X XDR *xdrsp; X struct simple *simplep; X{ X if (!xdr_int(xdrsp, &simplep->a)) X return (0); X if (!xdr_short(xdrsp, &simplep->b)) X return (0); X return (1); X} X.Lf X.BE X.LP XAn XDR routine returns nonzero (true in the sense of C) Xif it completes successfully, and zero otherwise. XA complete description of XDR is in the X.I "XDR Protocol Specification" , Xso this section only gives a few examples of XDR implementation. X.LP XIn addition to the built-in primitives, Xthere are also the prefabricated building blocks: X.BS X.LS Xxdr_array() xdr_bytes() Xxdr_reference() xdr_union() X.Lf X.BE XTo send a variable array of integers, Xyou might package them up as a structure like this X.BS X.LS Xstruct varintarr { X int *data; X int arrlnth; X} arr; X.Lf X.BE Xand make an RPC call such as X.BS X.LS Xcallrpc(hostname, PROGNUM, VERSNUM, PROCNUM, X xdr_varintarr, &arr...); X.Lf X.BE Xwith X.LW xdr_varintarr() Xdefined as: X.BS X.LS Xxdr_varintarr(xdrsp, arrp) X XDR *xdrsp; X struct varintarr *arrp; X{ X xdr_array(xdrsp, &arrp->data, &arrp->arrlnth, MAXLEN, X sizeof(int), xdr_int); X} X.Lf X.BE XThis routine takes as parameters the XDR handle, Xa pointer to the array, a pointer to the size of the array, Xthe maximum allowable array size, Xthe size of each array element, Xand an XDR routine for handling each array element. X.LP XIf the size of the array is known in advance, then Xthe following could also be used to send Xout an array of length X.LW SIZE : X.BS X.LS Xint intarr[SIZE]; X.sp.5 Xxdr_intarr(xdrsp, intarr) X XDR *xdrsp; X int intarr[]; X{ X int i; X.sp.5 X for (i = 0; i < SIZE; i++) { X if (!xdr_int(xdrsp, &intarr[i])) X return (0); X } X return (1); X} X.Lf X.BE X.LP XXDR always converts quantities to 4-byte multiples when deserializing. XThus, if either of the examples above involved characters Xinstead of integers, each character would occupy 32 bits. XThat is the reason for the XDR routine X.LW xdr_bytes() , Xwhich is like X.LW xdr_array() Xexcept that it packs characters; X.LW xdr_bytes() Xhas four parameters, similar to the first four parameters of X.LW xdr_array() . XFor null-terminated strings, there is also the X.LW xdr_string() Xroutine, which is the same as X.LW xdr_bytes() Xwithout the length parameter. XOn serializing it gets the string length from X.LW strlen() , Xand on deserializing it creates a null-terminated string. X.LP XHere is a final example that calls the previously written X.LW xdr_simple() Xas well as the built-in functions X.LW xdr_string() Xand X.LW xdr_reference() , Xwhich chases pointers: X.BS X.LS Xstruct finalexample { X char *string; X struct simple *simplep; X} finalexample; X.sp.5 Xxdr_finalexample(xdrsp, finalp) X XDR *xdrsp; X struct finalexample *finalp; X{ X int i; X.sp.5 X if (!xdr_string(xdrsp, &finalp->string, MAXSTRLEN)) X return (0); X if (!xdr_reference(xdrsp, &finalp->simplep, X sizeof(struct simple), xdr_simple); X return (0); X return (1); X} X.Lf X.BE X.bp X.NH XLowest Layer of RPC X.LP XIn the examples given so far, XRPC takes care of many details automatically for you. XIn this section, we'll show you how you can change the defaults Xby using lower layers of the RPC library. XIt is assumed that you are familiar with sockets Xand the system calls for dealing with them. XIf not, consult the X.I "IPC Primer" . X.LP XThere are several occasions when you may need to use lower layers of RPC. XFirst, you may need to use TCP. XThe higher layer uses UDP, Xwhich restricts RPC calls to 8K bytes of data. XUsing TCP permits calls to send long streams of data. XFor an example, see section 5.2 below. XSecond, you may want to allocate and free memory Xwhile serializing or deserializing with XDR routines. XThere is no call at the higher level to let you free memory explicitly. XFor more explanation, see section 3.2 below. XThird, you may need to perform authentication Xon either the client or server side, Xby supplying credentials or verifying them. XSee the explanation in section 4.4 below. X.NH 2 XMore on the Server Side X.LP XThe server for the X.LW nusers Xprogram shown below does the same thing as the one using X.LW registerrpc() Xabove, but is written using a lower layer of the RPC package: X.BS X.LS no X#include <stdio.h> X#include <rpc/rpc.h> X#include <rpcsvc/rusers.h> X.sp.5 Xmain() X{ X SVCXPRT *transp; X int nuser(); X.sp.5 X transp = svcudp_create(RPC_ANYSOCK); X if (transp == NULL){ X fprintf(stderr, "can't create an RPC server\en"); X exit(1); X } X pmap_unset(RUSERSPROG, RUSERSVERS); X if (!svc_register(transp, RUSERSPROG, RUSERSVERS, X nuser, IPPROTO_UDP)) { X fprintf(stderr, "can't register RUSER service\en"); X exit(1); X } X svc_run(); /* never returns */ X fprintf(stderr, "should never reach this point\en"); X} X.sp.5 Xnuser(rqstp, tranp) X struct svc_req *rqstp; X SVCXPRT *transp; X{ X unsigned long nusers; X.sp.5 X switch (rqstp->rq_proc) { X case NULLPROC: X if (!svc_sendreply(transp, xdr_void, 0)) { X fprintf(stderr, "can't reply to RPC call\en"); X exit(1); X } X return; X case RUSERSPROC_NUM: X /* X * code here to compute the number of users X * and put in variable nusers X */ X if (!svc_sendreply(transp, xdr_u_long, &nusers) { X fprintf(stderr, "can't reply to RPC call\en"); X exit(1); X } X return; X default: X svcerr_noproc(transp); X return; X } X} X.Lf X.BE X.LP XFirst, the server gets a transport handle, which is used Xfor sending out RPC messages. X.LW registerrpc() Xuses X.LW svcudp_create() Xto get a UDP handle. XIf you require a reliable protocol, call X.LW svctcp_create() Xinstead. XIf the argument to X.LW svcudp_create() Xis X.LW RPC_ANYSOCK , Xthe RPC library creates a socket Xon which to send out RPC calls. XOtherwise, X.LW svcudp_create() Xexpects its argument to be a valid socket number. XIf you specify your own socket, it can be bound or unbound. XIf it is bound to a port by the user, the port numbers of X.LW svcudp_create() Xand X.LW clntudp_create() X(the low-level client routine) must match. X.LP XWhen the user specifies X.LW RPC_ANYSOCK Xfor a socket or gives an unbound socket, Xthe system determines port numbers in the following way: Xwhen a server starts up, Xit advertises to a port mapper demon on its local machine, Xwhich picks a port number for the RPC procedure Xif the socket specified to X.LW svcudp_create() Xisn't already bound. XWhen the X.LW clntudp_create() Xcall is made with an unbound socket, Xthe system queries the port mapper on Xthe machine to which the call is being made, Xand gets the appropriate port number. XIf the port mapper is not running Xor has no port corresponding to the RPC call, Xthe RPC call fails. XUsers can make RPC calls Xto the port mapper themselves. XThe appropriate procedure Xnumbers are in the include file X.LW <rpc/pmap_prot.h> . X.LP XAfter creating an X.LW SVCXPRT , Xthe next step is to call X.LW pmap_unset() Xso that if the X.LW nusers Xserver crashed earlier, Xany previous trace of it is erased before restarting. XMore precisely, X.LW pmap_unset() Xerases the entry for X.LW RUSERSPROG Xfrom the port mapper's tables. X.LP XFinally, we associate the program number for X.LW nusers Xwith the procedure X.LW nuser() . XThe final argument to X.LW svc_register() Xis normally the protocol being used, Xwhich, in this case, is X.LW IPPROTO_UDP . XNotice that unlike X.LW registerrpc() , Xthere are no XDR routines involved Xin the registration process. XAlso, registration is done on the program, Xrather than procedure, level. X.LP XThe user routine X.LW nuser() Xmust call and dispatch the appropriate XDR routines Xbased on the procedure number. XNote that Xtwo things are handled by X.LW nuser() Xthat X.LW registerrpc() Xhandles automatically. XThe first is that procedure X.LW NULLPROC X(currently zero) returns with no arguments. XThis can be used as a simple test Xfor detecting if a remote program is running. XSecond, there is a check for invalid procedure numbers. XIf one is detected, X.LW svcerr_noproc() Xis called to handle the error. X.LP XThe user service routine serializes the results and returns Xthem to the RPC caller via X.LW svc_sendreply() . XIts first parameter is the X.LW SVCXPRT Xhandle, the second is the XDR routine, Xand the third is a pointer to the data to be returned. XNot illustrated above is how a server Xhandles an RPC program that passes data. XAs an example, we can add a procedure X.LW RUSERSPROC_BOOL , Xwhich has an argument X.LW nusers , Xand returns X.LW TRUE Xor X.LW FALSE Xdepending on whether there are nusers logged on. XIt would look like this: X.BS X.LS Xcase RUSERSPROC_BOOL: { X int bool; X unsigned nuserquery; X.sp.5 X if (!svc_getargs(transp, xdr_u_int, &nuserquery) { X svcerr_decode(transp); X return; X } X /* X * code to set nusers = number of users X */ X if (nuserquery == nusers) X bool = TRUE; X else X bool = FALSE; X if (!svc_sendreply(transp, xdr_bool, &bool){ X fprintf(stderr, "can't reply to RPC call\en"); X exit(1); X } X return; X} X.Lf X.BE X.LP XThe relevant routine is X.LW svc_getargs() , Xwhich takes an X.LW SVCXPRT Xhandle, the XDR routine, Xand a pointer to where the input is to be placed as arguments. X.NH 2 XMemory Allocation with XDR X.LP XXDR routines not only do input and output, Xthey also do memory allocation. XThis is why the second parameter of X.LW xdr_array() Xis a pointer to an array, rather than the array itself. XIf it is X.LW NULL , Xthen X.LW xdr_array() Xallocates space for the array and returns a pointer to it, Xputting the size of the array in the third argument. XAs an example, consider the following XDR routine X.LW xdr_chararr1() , Xwhich deals with a fixed array of bytes with length X.LW SIZE : X.BS X.LS Xxdr_chararr1(xdrsp, chararr) X XDR *xdrsp; X char chararr[]; X{ X char *p; X int len; X.sp.5 X p = chararr; X len = SIZE; X return (xdr_bytes(xdrsp, &p, &len, SIZE)); X} X.Lf X.BE XIt might be called from a server like this, X.BS X.LS Xchar chararr[SIZE]; X.sp.5 Xsvc_getargs(transp, xdr_chararr1, chararr); X.Lf X.BE Xwhere X.LW chararr Xhas already allocated space. XIf you want XDR to do the allocation, Xyou would have to rewrite this routine in the following way: X.BS X.LS Xxdr_chararr2(xdrsp, chararrp) X XDR *xdrsp; X char **chararrp; X{ X int len; X.sp.5 X len = SIZE; X return (xdr_bytes(xdrsp, charrarrp, &len, SIZE)); X} X.Lf X.BE XThen the RPC call might look like this: X.BS X.LS Xchar *arrptr; X.sp.5 Xarrptr = NULL; Xsvc_getargs(transp, xdr_chararr2, &arrptr); X/* X * use the result here X */ Xsvc_freeargs(transp, xdr_chararr2, &arrptr); X.Lf X.BE XAfter using the character array, it can be freed with X.LW svc_freeargs() . XIn the routine X.LW xdr_finalexample() Xgiven earlier, if X.LW finalp->string Xwas X.LW NULL Xin the call X.BS X.LS Xsvc_getargs(transp, xdr_finalexample, &finalp); X.Lf X.BE Xthen X.BS X.LS Xsvc_freeargs(xdrsp, xdr_finalexample, &finalp); X.Lf X.BE Xfrees the array allocated to hold X.LW finalp->string ; Xotherwise, it frees nothing. XThe same is true for X.LW finalp->simplep . X.LP XTo summarize, each XDR routine is responsible Xfor serializing, deserializing, and allocating memory. XWhen an XDR routine is called from X.LW callrpc() , Xthe serializing part is used. XWhen called from X.LW svc_getargs() , Xthe deserializer is used. XAnd when called from X.LW svc_freeargs() , Xthe memory deallocator is used. XWhen building simple examples like those in this section, Xa user doesn't have to worry about the three modes. XThe XDR reference manual has examples of more Xsophisticated XDR routines that Xdetermine which of the three modes they are in Xto function correctly. X.NH 2 XThe Calling Side X.LP XWhen you use X.LW callrpc() , Xyou have no control over the RPC delivery Xmechanism or the socket used to transport the data. XTo illustrate the layer of RPC that lets you adjust these Xparameters, consider the following code to call the X.LW nusers Xservice: X.BS X.LS no X#include <stdio.h> X#include <rpc/rpc.h> X#include <rpcsvc/rusers.h> X#include <sys/socket.h> X#include <sys/time.h> X#include <netdb.h> X.sp.5 Xmain(argc, argv) X int argc; X char **argv; X{ X struct hostent *hp; X struct timeval pertry_timeout, total_timeout; X struct sockaddr_in server_addr; X int addrlen, sock = RPC_ANYSOCK; X register CLIENT *client; X enum clnt_stat clnt_stat; X unsigned long nusers; X.sp.5 X if (argc < 2) { X fprintf(stderr, "usage: nusers hostname\en"); X exit(-1); X } X if ((hp = gethostbyname(argv[1])) == NULL) { X fprintf(stderr, "can't get addr for %s\en",argv[1]); X exit(-1); X } X pertry_timeout.tv_sec = 3; X pertry_timeout.tv_usec = 0; X addrlen = sizeof(struct sockaddr_in); X bcopy(hp->h_addr, (caddr_t)&server_addr.sin_addr, X hp->h_length); X server_addr.sin_family = AF_INET; X server_addr.sin_port = 0; X if ((client = clntudp_create(&server_addr, RUSERSPROG, X RUSERSVERS, pertry_timeout, &sock)) == NULL) { X clnt_pcreateerror("clntudp_create"); X exit(-1); X } X total_timeout.tv_sec = 20; X total_timeout.tv_usec = 0; X clnt_stat = clnt_call(client, RUSERSPROC_NUM, xdr_void, X 0, xdr_u_long, &nusers, total_timeout); X if (clnt_stat != RPC_SUCCESS) { X clnt_perror(client, "rpc"); X exit(-1); X } X clnt_destroy(client); X} X.Lf X.BE XThe low-level version of X.LW callrpc() Xis X.LW clnt_call() , Xwhich takes a X.LW CLIENT Xpointer rather than a host name. The parameters to X.LW clnt_call() Xare a X.LW CLIENT Xpointer, the procedure number, Xthe XDR routine for serializing the argument, Xa pointer to the argument, Xthe XDR routine for deserializing the return value, Xa pointer to where the return value will be placed, Xand the time in seconds to wait for a reply. X.LP XThe X.LW CLIENT Xpointer is encoded with the transport mechanism. X.LW callrpc() Xuses UDP, thus it calls X.LW clntudp_create() Xto get a X.LW CLIENT Xpointer. To get TCP (Transport Control Protocol), you would use X.LW clnttcp_create() . X.LP XThe parameters to X.LW clntudp_create() Xare the server address, the length of the server address, Xthe program number, the version number, Xa timeout value (between tries), and a pointer to a socket. XThe final argument to X.LW clnt_call() Xis the total time to wait for a response. XThus, the number of tries is the X.LW clnt_call() Xtimeout divided by the X.LW clntudp_create() Xtimeout. X.LP XThere is one thing to note when using the X.LW clnt_destroy() Xcall. XIt deallocates any space associated with the X.LW CLIENT Xhandle, but it does not close the socket associated with it, Xwhich was passed as an argument to X.LW clntudp_create() . XThe reason is that if Xthere are multiple client handles using the same socket, Xthen it is possible to close one handle Xwithout destroying the socket that other handles Xare using. X.LP XTo make a stream connection, the call to X.LW clntudp_create() Xis replaced with a call to X.LW clnttcp_create() . X.BS X.LS Xclnttcp_create(&server_addr, prognum, versnum, &socket, X inputsize, outputsize); X.Lf X.BE XThere is no timeout argument; instead, the receive and send buffer Xsizes must be specified. When the X.LW clnttcp_create() Xcall is made, a TCP connection is established. XAll RPC calls using that X.LW CLIENT Xhandle would use this connection. XThe server side of an RPC call using TCP has X.LW svcudp_create() Xreplaced by X.LW svctcp_create() . X.bp X.NH XOther RPC Features X.LP XThis section discusses some other aspects of RPC Xthat are occasionally useful. X.NH 2 XSelect on the Server Side X.LP XSuppose a process is processing RPC requests Xwhile performing some other activity. XIf the other activity involves periodically updating a data structure, Xthe process can set an alarm signal before calling X.LW svc_run() . XBut if the other activity Xinvolves waiting on a a file descriptor, the X.LW svc_run() Xcall won't work. XThe code for X.LW svc_run() Xis as follows: X.BS X.LS Xvoid Xsvc_run() X{ X int readfds; X.sp.5 X for (;;) { X readfds = svc_fds; X switch (select(32, &readfds, NULL, NULL, NULL)) { X.sp.5 X case -1: X if (errno == EINTR) X continue; X perror("rstat: select"); X return; X case 0: X break; X default: X svc_getreq(readfds); X } X } X} X.Lf X.BE X.LP XYou can bypass X.LW svc_run() Xand call X.LW svc_getreq() Xyourself. XAll you need to know are the file descriptors Xof the socket(s) associated with the programs you are waiting on. XThus you can have your own X.LW select() Xthat waits on both the RPC socket, Xand your own descriptors. X.NH 2 XBroadcast RPC X.LP XThe X.I portmapper Xis a daemon that converts RPC program numbers Xinto DARPA protocol port numbers; see X.LW portmap (8). XYou can't do broadcast RPC without the portmapper, X.LW pmap , Xin conjunction with standard RPC protocols. XHere are the main differences between Xbroadcast RPC and normal RPC calls: X.IP 1. XNormal RPC expects one answer, whereas Xbroadcast RPC expects many answers X(one or more answer from each responding machine). X.IP 2. XBroadcast RPC can only be supported by packet-oriented (connectionless) Xtransport protocols like UPD/IP. X.IP 3. XThe implementation of broadcast RPC Xtreats all unsuccessful responses as garbage by filtering them out. XThus, if there is a version mismatch between the Xbroadcaster and a remote service, Xthe user of broadcast RPC never knows. X.IP 4. XAll broadcast messages are sent to the portmap port. XThus, only services that register themselves with their portmapper Xare accessible via the broadcast RPC mechanism. X.NH 3 XBroadcast RPC Synopsis X.LP X.BS X.LS X#include <rpc/pmap_clnt.h> X.sp.5 Xenum clnt_stat clnt_stat; X.sp.5 Xclnt_stat = Xclnt_broadcast(prog, vers, proc, xargs, argsp, xresults, X resultsp, eachresult) Xu_long prog; /* program number */ Xu_long vers; /* version number */ Xu_long proc; /* procedure number */ Xxdrproc_t xargs; /* xdr routine for args */ Xcaddr_t argsp; /* pointer to args */ Xxdrproc_t xresults; /* xdr routine for results */ Xcaddr_t resultsp; /* pointer to results */ Xbool_t (*eachresult)(); /* call with each result gotten */ X.Lf X.BE XThe procedure X.LW eachresult() Xis called each time a valid result is obtained. XIt returns a boolean that indicates Xwhether or not the client wants more responses. X.BS X.LS Xbool_t done; X.sp.5 Xdone = Xeachresult(resultsp, raddr) Xcaddr_t resultsp; Xstruct sockaddr_in *raddr; /* addr of responding machine */ X.Lf X.BE XIf X.LW done Xis X.LW TRUE , Xthen broadcasting stops and X.LW clnt_broadcast() Xreturns successfully. XOtherwise, the routine waits for another response. XThe request is rebroadcast Xafter a few seconds of waiting. XIf no responses come back, Xthe routine returns with X.LW RPC_TIMEDOUT . XTo interpret X.LW clnt_stat Xerrors, feed the error code to X.LW clnt_perrno() . X.NH 2 XBatching X.LP XThe RPC architecture is designed so that clients send a call message, Xand wait for servers to reply that the call succeeded. XThis implies that clients do not compute Xwhile servers are processing a call. XThis is inefficient if the client does not want or need Xan acknowledgement for every message sent. XIt is possible for clients to continue computing Xwhile waiting for a response, Xusing RPC batch facilities. X.LP XRPC messages can be placed in a ``pipeline'' of calls Xto a desired server; this is called batching. XBatching assumes that: X1) each RPC call in the pipeline requires no response from the server, Xand the server does not send a response message; and X2) the pipeline of calls is transported on a reliable Xbyte stream transport such as TCP/IP. XSince the server does not respond to every call, Xthe client can generate new calls in parallel Xwith the server executing previous calls. XFurthermore, the TCP/IP implementation can buffer up Xmany call messages, and send them to the server in one X.LW write() Xsystem call. This overlapped execution Xgreatly decreases the interprocess communication overhead of Xthe client and server processes, Xand the total elapsed time of a series of calls. X.LP XSince the batched calls are buffered, Xthe client should eventually do a legitimate call Xin order to flush the pipeline. X.LP XA contrived example of batching follows. XAssume a string rendering service (like a window system) Xhas two similar calls: one renders a string and returns void results, Xwhile the other renders a string and remains silent. XThe service (using the TCP/IP transport) may look like: X.BS X.LS no X#include <stdio.h> X#include <rpc/rpc.h> X#include <rpcsvc/windows.h> X.sp.5 Xvoid windowdispatch(); X.sp.5 Xmain() X{ X SVCXPRT *transp; X.sp.5 X transp = svctcp_create(RPC_ANYSOCK, 0, 0); X if (transp == NULL){ X fprintf(stderr, "can't create an RPC server\en"); X exit(1); X } X pmap_unset(WINDOWPROG, WINDOWVERS); X if (!svc_register(transp, WINDOWPROG, WINDOWVERS, X windowdispatch, IPPROTO_TCP)) { X fprintf(stderr, "can't register WINDOW service\en"); X exit(1); X } X svc_run(); /* never returns */ X fprintf(stderr, "should never reach this point\en"); X} X.sp.5 Xvoid Xwindowdispatch(rqstp, transp) X struct svc_req *rqstp; X SVCXPRT *transp; X{ X char *s = NULL; X.sp.5 X switch (rqstp->rq_proc) { X case NULLPROC: X if (!svc_sendreply(transp, xdr_void, 0)) { X fprintf(stderr, "can't reply to RPC call\en"); X exit(1); X } X return; X case RENDERSTRING: X if (!svc_getargs(transp, xdr_wrapstring, &s)) { X fprintf(stderr, "can't decode arguments\en"); X /* X * tell caller he screwed up X */ X svcerr_decode(transp); X break; X } X /* X * call here to render the string s X */ X if (!svc_sendreply(transp, xdr_void, NULL)) { X fprintf(stderr, "can't reply to RPC call\en"); X exit(1); X } X break; X case RENDERSTRING_BATCHED: X if (!svc_getargs(transp, xdr_wrapstring, &s)) { X fprintf(stderr, "can't decode arguments\en"); X /* X * we are silent in the face of protocol errors X */ X break; X } X /* X * call here to render string s, but send no reply! X */ X break; X default: X svcerr_noproc(transp); X return; X } X /* X * now free string allocated while decoding arguments X */ X svc_freeargs(transp, xdr_wrapstring, &s); X} X.Lf X.BE XOf course the service could have one procedure Xthat takes the string and a boolean Xto indicate whether or not the procedure should respond. X.LP XIn order for a client to take advantage of batching, Xthe client must perform RPC calls on a TCP-based transport Xand the actual calls must have the following attributes: X1) the result's XDR routine must be zero X.LW NULL ), ( Xand 2) the RPC call's timeout must be zero. X.LP XHere is an example of a client that uses batching Xto render a bunch of strings; Xthe batching is flushed when the client gets a null string: X.BS X.LS no X#include <stdio.h> X#include <rpc/rpc.h> X#include <rpcsvc/windows.h> X#include <sys/socket.h> X#include <sys/time.h> X#include <netdb.h> X.sp.5 Xmain(argc, argv) X int argc; X char **argv; X{ X struct hostent *hp; X struct timeval pertry_timeout, total_timeout; X struct sockaddr_in server_addr; X int addrlen, sock = RPC_ANYSOCK; X register CLIENT *client; X enum clnt_stat clnt_stat; X char buf[1000], *s = buf; X.sp.5 X /* initial as in example 3.3 X */ X if ((client = clnttcp_create(&server_addr, X WINDOWPROG, WINDOWVERS, &sock, 0, 0)) == NULL) { X perror("clnttcp_create"); X exit(-1); X } X total_timeout.tv_sec = 0; X total_timeout.tv_usec = 0; X while (scanf("%s", s) != EOF) { X clnt_stat = clnt_call(client, RENDERSTRING_BATCHED, X xdr_wrapstring, &s, NULL, NULL, total_timeout); X if (clnt_stat != RPC_SUCCESS) { X clnt_perror(client, "batched rpc"); X exit(-1); X } X } X /* now flush the pipeline X */ X total_timeout.tv_sec = 20; X clnt_stat = clnt_call(client, NULLPROC, xdr_void, NULL, X xdr_void, NULL, total_timeout); X if (clnt_stat != RPC_SUCCESS) { X clnt_perror(client, "rpc"); X exit(-1); X } X clnt_destroy(client); X} X.Lf X.BE XSince the server sends no message, Xthe clients cannot be notified of any of the failures that may occur. XTherefore, clients are on their own when it comes to handling errors. X.LP XThe above example was completed to render Xall of the (2000) lines in the file X.I /etc/termcap . XThe rendering service did nothing but throw the lines away. XThe example was run in the following four configurations: X1) machine to itself, regular RPC; X2) machine to itself, batched RPC; X3) machine to another, regular RPC; and X4) machine to another, batched RPC. XThe results are as follows: X1) 50 seconds; X2) 16 seconds; X3) 52 seconds; X4) 10 seconds. XRunning X.LW fscanf() Xon X.I /etc/termcap Xonly requires six seconds. XThese timings show the advantage of protocols Xthat allow for overlapped execution, Xthough these protocols are often hard to design. X.NH 2 XAuthentication X.LP XIn the examples presented so far, Xthe caller never identified itself to the server, Xand the server never required an ID from the caller. XClearly, some network services, such as a network filesystem, Xrequire stronger security than what has been presented so far. X.LP XIn reality, every RPC call is authenticated by Xthe RPC package on the server, and similarly, Xthe RPC client package generates and sends authentication parameters. XJust as different transports (TCP/IP or UDP/IP) Xcan be used when creating RPC clients and servers, Xdifferent forms of authentication can be associated with RPC clients; Xthe default authentication type used as a default is type X.I none . X.LP XThe authentication subsystem of the RPC package is open ended. XThat is, numerous types of authentication are easy to support. XHowever, this section deals only with X.I unix Xtype authentication, which besides X.I none Xis the only supported type. X.NH 3 XThe Client Side X.LP XWhen a caller creates a new RPC client handle as in: X.BS X.LS Xclnt = clntudp_create(address, prognum, versnum, X wait, sockp) X.Lf X.BE Xthe appropriate transport instance defaults Xthe associate authentication handle to be X.BS X.LS Xclnt->cl_auth = authnone_create(); X.Lf X.BE XThe RPC client can choose to use X.I unix Xstyle authentication by setting X.LW clnt->cl_auth Xafter creating the RPC client handle: X.BS X.LS Xclnt->cl_auth = authunix_create_default(); X.Lf X.BE XThis causes each RPC call associated with X.LW clnt Xto carry with it the following authentication credentials structure: X.BS X.LS X/* X * Unix style credentials. X */ Xstruct authunix_parms { X u_long aup_time; /* credentials creation time */ X char *aup_machname; /* host name where client is */ X int aup_uid; /* client's UNIX effective uid */ X int aup_gid; /* client's current group id */ X u_int aup_len; /* element length of aup_gids */ X int *aup_gids; /* array of groups user is in */ X}; X.Lf X.BE XThese fields are set by X.LW authunix_create_default() Xby invoking the appropriate system calls. XSince the RPC user created this new style of authentication, Xthe user is responsible for destroying it with: X.BS X.LS Xauth_destroy(clnt->cl_auth); X.Lf X.BE XThis should be done in all cases, to conserve memory. X.NH 3 XThe Server Side X.LP XService implementors have a harder time dealing with authentication issues Xsince the RPC package passes the service dispatch routine a request Xthat has an arbitrary authentication style associated with it. XConsider the fields of a request handle passed to a service dispatch routine: X.BS X.LS X/* X * An RPC Service request X */ Xstruct svc_req { X u_long rq_prog; /* service program number */ X u_long rq_vers; /* service protocol vers num */ X u_long rq_proc; /* desired procedure number */ X struct opaque_auth X rq_cred; /* raw credentials from wire */ X caddr_t rq_clntcred; /* credentials (read only) */ X}; X.Lf X.BE XThe X.LW rq_cred Xis mostly opaque, except for one field of interest: Xthe style of authentication credentials: X.BS X.LS X/* X * Authentication info. Mostly opaque to the programmer. X */ Xstruct opaque_auth { X enum_t oa_flavor; /* style of credentials */ X caddr_t oa_base; /* address of more auth stuff */ X u_int oa_length; /* not to exceed MAX_AUTH_BYTES */ X}; X.Lf X.BE XThe RPC package guarantees the following Xto the service dispatch routine: X.IP 1. XThat the request's X.LW rq_cred Xis well formed. Thus the service implementor may inspect the request's X.LW rq_cred.oa_flavor Xto determine which style of authentication the caller used. XThe service implementor may also wish to inspect the other fields of X.LW rq_cred Xif the style is not one of the styles supported by the RPC package. X.IP 2. XThat the request's X.LW rq_clntcred Xfield is either X.LW NULL Xor points to a well formed structure Xthat corresponds to a supported style of authentication credentials. XRemember that only X.I unix Xstyle is currently supported, so (currently) X.LW rq_clntcred Xcould be cast to a pointer to an X.LW authunix_parms Xstructure. If X.LW rq_clntcred Xis X.LW NULL , Xthe service implementor may wish to inspect the other (opaque) fileds of X.LW rq_cred Xin case the service knows about a new type of authentication Xthat the RPC package does not know about. X.LP XOur remote users service example can be extended so that Xit computes results for all users except UID 16: X.BS X.LS no Xnuser(rqstp, tranp) X struct svc_req *rqstp; X SVCXPRT *transp; X{ X struct authunix_parms *unix_cred; X int uid; X unsigned long nusers; X.sp.5 X /* X * we don't care about authentication for null proc X */ X if (rqstp->rq_proc == NULLPROC) { X if (!svc_sendreply(transp, xdr_void, 0)) { X fprintf(stderr, "can't reply to RPC call\en"); X exit(1); X } X return; X } X /* X * now get the uid X */ X switch (rqstp->rq_cred.oa_flavor) { X case AUTH_UNIX: X unix_cred = (struct authunix_parms *)rqstp->rq_clntcred; X uid = unix_cred->aup_uid; X break; X case AUTH_NULL: X default: X svcerr_weakauth(transp); X return; X } X switch (rqstp->rq_proc) { X case RUSERSPROC_NUM: X /* X * make sure caller is allowed to call this proc X */ X if (uid == 16) { X svcerr_systemerr(transp); X return; X } X /* X * code here to compute the number of users X * and put in variable nusers X */ X if (!svc_sendreply(transp, xdr_u_long, &nusers) { X fprintf(stderr, "can't reply to RPC call\en"); X exit(1); X } X return; X default: X svcerr_noproc(transp); X return; X } X} X.Lf X.BE XA few things should be noted here. XFirst, it is customary not to check Xthe authentication parameters associated with the X.LW NULLPROC X(procedure number zero). XSecond, if the authentication parameter's type is not suitable Xfor your service, you should call X.LW svcerr_weakauth() . XAnd finally, the service protocol itself should return status Xfor access denied; in the case of our example, the protocol Xdoes not have such a status, so we call the service primitive X.LW svcerr_systemerr() Xinstead. X.LP XThe last point underscores the relation between Xthe RPC authentication package and the services; XRPC deals only with authentication and not with Xindividual services' access control. XThe services themselves must implement their own access control policies Xand reflect these policies as return statuses in their protocols. X.NH 2 XUsing Inetd X.LP XAn RPC server can be started from X.LW inetd . XThe only difference Xfrom the usual code is that X.LW svcudp_create() Xshould be called as X.BS X.LS Xtransp = svcudp_create(0); X.Lf X.BE Xsince X.LW inet Xpasses a socket as file descriptor 0. XAlso, X.LW svc_register() Xshould be called as X.BS X.LS Xsvc_register(transp, PROGNUM, VERSNUM, service, 0); X.Lf X.BE Xwith the final flag as 0, Xsince the program would already be registered by X.LW inetd . XRemember that if you want to exit Xfrom the server process and return control to X.LW inet , Xyou need to explicitly exit, since X.LW svc_run() Xnever returns. X.LP XThe format of entries in /etc/servers for RPC services is X.BS X.LS Xrpc udp \fIserver \0program \0version\fP X.Lf X.BE Xwhere X.I server Xis the C code implementing the server, Xand X.I program Xand X.I version Xare the program and version numbers of the service. XThe key word X.LW udp Xcan be replaced by X.LW tcp Xfor TCP-based RPC services. X.LP XIf the same program handles multiple versions, Xthen the version number can be a range, Xas in this example: X.BS X.LS Xrpc udp /usr/etc/rstatd 100001 1-2 X.Lf X.BE X.bp X.NH XMore Examples X.NH 2 XVersions X.LP XBy convention, the first version number of program X.LW PROG Xis X.LW PROGVERS_ORIG Xand the most recent version is X.LW PROGVERS . XSuppose there is a new version of the X.LW user Xprogram that returns an X.LW "unsigned short" Xrather than a X.LW long . XIf we name this version X.LW RUSERSVERS_SHORT , Xthen a server that wants to support both versions Xwould do a double register. X.BS X.LS Xif (!svc_register(transp, RUSERSPROG, RUSERSVERS_ORIG, X nuser, IPPROTO_TCP)) { X fprintf(stderr, "can't register RUSER service\en"); X exit(1); X} Xif (!svc_register(transp, RUSERSPROG, RUSERSVERS_SHORT, X nuser, IPPROTO_TCP)) { X fprintf(stderr, "can't register RUSER service\en"); X exit(1); X} X.Lf X.BE XBoth versions can be handled by the same C procedure: X.BS X.LS no Xnuser(rqstp, tranp) X struct svc_req *rqstp; X SVCXPRT *transp; X{ X unsigned long nusers; X unsigned short nusers2 X.sp.5 X switch (rqstp->rq_proc) { X case NULLPROC: X if (!svc_sendreply(transp, xdr_void, 0)) { X fprintf(stderr, "can't reply to RPC call\en"); X exit(1); X } X return; X case RUSERSPROC_NUM: X /* X * code here to compute the number of users X * and put in variable nusers X */ X nusers2 = nusers; X if (rqstp->rq_vers != RUSERSVERS_ORIG) X return; X if (!svc_sendreply(transp, xdr_u_long, &nusers) { X fprintf(stderr, "can't reply to RPC call\en"); X exit(1); X } else X if (!svc_sendreply(transp, xdr_u_short, &nusers2) { X fprintf(stderr, "can't reply to RPC call\en"); X exit(1); X } X return; X default: X svcerr_noproc(transp); X return; X } X} X.Lf X.BE X.NH 2 XTCP X.LP XHere is an example that is essentially X.LW rcp . XThe initiator of the RPC X.LW snd() Xcall takes its standard input and sends it to the server X.LW rcv() , Xwhich prints it on standard output. XThe RPC call uses TCP. XThis also illustrates an XDR procedure that behaves differently Xon serialization than on deserialization. X.BS X.LS no X/* X * The xdr routine: X * on decode, read from wire, write onto fp X * on encode, read from fp, write onto wire X */ X#include <stdio.h> X#include <rpc/rpc.h> X.sp.5 Xxdr_rcp(xdrs, fp) X XDR *xdrs; X FILE *fp; X{ X unsigned long size; X char buf[BUFSIZ], *p; X.sp.5 X if (xdrs->x_op == XDR_FREE)/* nothing to free */ X return 1; X while (1) { X if (xdrs->x_op == XDR_ENCODE) { X if ((size = fread(buf, sizeof(char), BUFSIZ, X fp)) == 0 && ferror(fp)) { X fprintf(stderr, "can't fread\en"); X exit(1); X } X } X p = buf; X if (!xdr_bytes(xdrs, &p, &size, BUFSIZ)) X return 0; X if (size == 0) X return 1; X if (xdrs->x_op == XDR_DECODE) { X if (fwrite(buf, sizeof(char), size, X fp) != size) { X fprintf(stderr, "can't fwrite\en"); X exit(1); X } X } X } X} X.sp.5 X/* X * The sender routines X */ X#include <stdio.h> X#include <netdb.h> X#include <rpc/rpc.h> X#include <sys/socket.h> X#include <sys/time.h> X.sp.5 Xmain(argc, argv) X int argc; X char **argv; X{ X int err; X.sp.5 X if (argc < 2) { X fprintf(stderr, "usage: %s servername\en", argv[0]); X exit(-1); X } X if ((err = callrpctcp(argv[1], RCPPROG, RCPPROC_FP, X RCPVERS, xdr_rcp, stdin, xdr_void, 0) != 0)) { X clnt_perrno(err); X fprintf(stderr, "can't make RPC call\en"); X exit(1); X } X} X.sp.5 Xcallrpctcp(host, prognum, procnum, versnum, X inproc, in, outproc, out) X char *host, *in, *out; X xdrproc_t inproc, outproc; X{ X struct sockaddr_in server_addr; X int socket = RPC_ANYSOCK; X enum clnt_stat clnt_stat; X struct hostent *hp; X register CLIENT *client; X struct timeval total_timeout; X.sp.5 X if ((hp = gethostbyname(host)) == NULL) { X fprintf(stderr, "can't get addr for '%s'\en", host); X exit(-1); X } X bcopy(hp->h_addr, (caddr_t)&server_addr.sin_addr, X hp->h_length); X server_addr.sin_family = AF_INET; X server_addr.sin_port = 0; X if ((client = clnttcp_create(&server_addr, prognum, X versnum, &socket, BUFSIZ, BUFSIZ)) == NULL) { X perror("rpctcp_create"); X exit(-1); X } X total_timeout.tv_sec = 20; X total_timeout.tv_usec = 0; X clnt_stat = clnt_call(client, procnum, X inproc, in, outproc, out, total_timeout); X clnt_destroy(client) X return (int)clnt_stat; X} X.sp.5 X/* X * The receiving routines X */ X#include <stdio.h> X#include <rpc/rpc.h> X.sp.5 Xmain() X{ X register SVCXPRT *transp; X.sp.5 X if ((transp = svctcp_create(RPC_ANYSOCK, X BUFSIZ, BUFSIZ)) == NULL) { X fprintf("svctcp_create: error\en"); X exit(1); X } X pmap_unset(RCPPROG, RCPVERS); X if (!svc_register(transp, X RCPPROG, RCPVERS, rcp_service, IPPROTO_TCP)) { X fprintf(stderr, "svc_register: error\en"); X exit(1); X } X svc_run(); /* never returns */ X fprintf(stderr, "svc_run should never return\en"); X} X.sp.5 Xrcp_service(rqstp, transp) X register struct svc_req *rqstp; X register SVCXPRT *transp; X{ X switch (rqstp->rq_proc) { X case NULLPROC: X if (svc_sendreply(transp, xdr_void, 0) == 0) { X fprintf(stderr, "err: rcp_service"); X exit(1); X } X return; X case RCPPROC_FP: X if (!svc_getargs(transp, xdr_rcp, stdout)) { X svcerr_decode(transp); X return; X } X if (!svc_sendreply(transp, xdr_void, 0)) { X fprintf(stderr, "can't reply\en"); X return; X } X exit(0); X default: X svcerr_noproc(transp); X return; X } X} X.Lf X.BE X.NH 2 XCallback Procedures X.LP XOccasionally, it is useful to have a server become a client, Xand make an RPC call back the process which is its client. XAn example is remote debugging, Xwhere the client is a window system program, Xand the server is a debugger running on the remote machine. XMost of the time, Xthe user clicks a mouse button at the debugging window, Xwhich converts this to a debugger command, Xand then makes an RPC call to the server X(where the debugger is actually running), Xtelling it to execute that command. XHowever, when the debugger hits a breakpoint, the roles are reversed, Xand the debugger wants to make an rpc call to the window program, Xso that it can inform the user that a breakpoint has been reached. SHAR_EOF if test 49365 -ne "`wc -c < 'rpc/doc/rpc.prog.p1'`" then echo shar: "error transmitting 'rpc/doc/rpc.prog.p1'" '(should have been 49365 characters)' fi chmod 444 'rpc/doc/rpc.prog.p1' fi exit 0 # End of shell archive